/**
 * Copyright (C) 2013 Daniel Gee.
 * See LICENSE.txt for more details.
 */
package com.rl.dungeon.pathing;

import java.util.Collection;

import com.rl.dungeon.Location;

/**
 * Interface for an object that stores information about a movement mode and movement costs. This is
 * used to compute paths from one place to another.
 * 
 * @author Daniel Gee
 */
public interface MoveCostMap
{
	/**
	 * Returns a collection of all points that can be immediately moved to from the point specified.
	 * This allows the MoveCostGrid to account for movement blocking terrain, the edges of the grid,
	 * stairs, teleports, etc. If a location is provided that {@link #isWalkable(Location)} wouldn't
	 * return <tt>true</tt> for then an {@link IllegalArgumentException} should be thrown. All
	 * locations returned by this method must be "walkable" locations.
	 * 
	 * @param location
	 *            the location
	 * @return all locations that can be reached from this location.
	 */
	public Collection<Location> getLocationsAccessableFrom(Location location);

	/**
	 * Obtains the movement cost to enter the location specified. This must be non-negative. Usually
	 * this value is just 1 for all locations, but some things such as hindering terrain or magic
	 * effects can increase the movement cost. If a location is provided that
	 * {@link #isWalkable(Location)} wouldn't return <tt>true</tt> for then an
	 * {@link IllegalArgumentException} should be thrown.
	 * 
	 * @param location
	 *            the location
	 * @return the cost to enter the specified location.
	 */
	public int getMoveCostAt(Location location);

	/**
	 * Returns if the location specified is a valid, walkable location within this grid or not. In
	 * this case, "walkable" simply means usable for the movement mode that this {@link MoveCostMap}
	 * represents, be it actual walking, flying, burrowing, etc.
	 * 
	 * @param location
	 *            the location in question.
	 * @return <tt>true</tt> if the point is a valid location, <tt>false</tt> otherwise.
	 */
	public boolean isWalkable(Location location);
}
